"""
异常处理工具模块。
EN: Exception handling utility module.

该模块提供了一个上下文管理器 `LogException`，用于统一处理和记录代码块中发生的异常。
可以配置是否记录错误日志，方便在需要忽略异常或仅记录不中断程序的情况下使用。
EN: This module provides a context manager `LogException` for unified handling and logging of exceptions
that occur within a code block. It can be configured to log errors or not, making it useful for scenarios
where exceptions need to be ignored or only logged without interrupting program execution.
"""

# 导入日志模块，用于记录程序运行时的信息
# EN: Import the logging module, used for recording information during program execution
import logging

# 获取当前模块的 logger 实例
# EN: Get the logger instance for the current module
log = logging.getLogger(__name__)


class LogException:
    """
    一个上下文管理器，用于捕获并可选地记录代码块中的异常。
    EN: A context manager for catching and optionally logging exceptions within a code block.

    使用示例:
    EN: Example usage:
    ```python
    with LogException():
        # 可能会抛出异常的代码
        # EN: Code that might raise an exception
        1 / 0

    with LogException(log_error=False):
        # 忽略异常，不记录日志
        # EN: Ignore exception, do not log
        int('abc')
    ```
    """

    def __init__(self, log_error: bool = True):
        """
        初始化 LogException 实例。
        EN: Initializes a LogException instance.

        Args:
            log_error (bool, optional): 是否记录捕获到的异常。默认为 True。
            EN: log_error (bool, optional): Whether to log caught exceptions. Defaults to True.
        """
        self.log_error = log_error

    def __enter__(self):
        """
        进入上下文管理器时执行的方法。
        EN: Method executed when entering the context manager.

        此方法不执行任何操作。
        EN: This method does nothing.
        """
        pass

    def __exit__(self, exc_type, exc_val, exc_tb):
        """
        退出上下文管理器时执行的方法，用于处理异常。
        EN: Method executed when exiting the context manager, used for handling exceptions.

        如果发生异常 (`exc_type` 不为 None) 且 `log_error` 为 True，则记录错误日志。
        始终返回 True，表示已处理异常，阻止异常向上传播。
        EN: If an exception occurs (`exc_type` is not None) and `log_error` is True, an error log is recorded.
        Always returns True, indicating that the exception has been handled and preventing it from propagating further.

        Args:
            exc_type (type): 异常类型。
            EN: exc_type (type): The exception type.
            exc_val (Exception): 异常实例。
            EN: exc_val (Exception): The exception instance.
            exc_tb (traceback): 异常的追踪信息。
            EN: exc_tb (traceback): The traceback information for the exception.

        Returns:
            bool: 始终返回 True，表示异常已被处理。
            EN: bool: Always returns True, indicating that the exception has been handled.
        """
        # 如果存在异常类型且需要记录错误日志
        # EN: If an exception type exists and error logging is enabled
        if exc_type and self.log_error:
            # 记录错误日志，包括异常信息和追踪信息
            # EN: Log the error, including exception information and traceback
            log.error('An exception occurred', exc_info=(exc_type, exc_val, exc_tb))
        # 返回 True，表示异常已被处理，不会向外传播
        # EN: Return True, indicating that the exception has been handled and will not propagate outwards
        return True


# LogException 的一个实例，用于记录错误日志并捕获异常
# EN: An instance of LogException, used to log errors and catch exceptions
log_exception = LogException()
# LogException 的另一个实例，用于捕获异常但不记录错误日志
# EN: Another instance of LogException, used to catch exceptions but not log errors
ignore_exception = LogException(log_error=False)
